<!DOCTYPE html>
<html lang="en" itemscope itemtype="https://schema.org/WebPage">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Vitess / Running Vitess on a Local Server</title>

        <!-- Webfont -->
    <link href='http://fonts.googleapis.com/css?family=Roboto:400,100,100italic,300,300italic,400italic,500,500italic,700,700italic,900,900italic' rel='stylesheet' type='text/css'>
    
    <!--<link rel="shortcut icon" type="image/png" href="/favicon.png">-->

    <!-- Bootstrap -->
    <link href="/libs/bootstrap/css/bootstrap.min.css" rel="stylesheet">

    <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
    <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
    <!--[if lt IE 9]>
      <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
      <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->

    <!-- Styles -->
    <link rel="stylesheet" type="text/css" href="/css/site.css" />
    <!-- Font Awesome icons -->
    <link href="/libs/font-awesome-4.4.0/css/font-awesome.min.css"
          rel="stylesheet"
          type="text/css">
    
    <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
    <!-- Include all compiled plugins (below), or include individual files as needed -->
    <script src="/libs/bootstrap/js/bootstrap.min.js"></script>


    <!-- metadata -->
    <meta name="og:title" content="Vitess / Running Vitess on a Local Server"/>
    <meta name="og:image" content="/images/vitess_logo_with_border.svg"/>
    <meta name="og:description" content="Vitess is a database clustering system for horizontal scaling of MySQL."/>

    <link rel="icon" href="/images/vitess_logo_icon_size.png" type="image/png">

    
    <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
  ga('create', 'UA-60219601-1', 'auto');
  ga('send', 'pageview');
</script>

    
  </head>
  <body class="docs" id="top_of_page">

    <span id="toc-depth" data-toc-depth="h2,h3"></span>


    <nav id="common-nav" class="navbar navbar-fixed-top inverse">
  <div class="container">
    <!-- Brand and toggle get grouped for better mobile display -->
    <div class="navbar-header">
      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-collapse-1">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a class="navbar-brand" href="/">
        <img class="logo" src="/images/vitess_logo_with_border.svg" alt="Vitess">
      </a>
    </div>

    <!-- Collect the nav links, forms, and other content for toggling -->
    <div class="collapse navbar-collapse" id="navbar-collapse-1">
      <ul class="nav navbar-nav navbar-right" id="standard-menu-links">
        <li><a href="/overview/">Overview</a></li>
        <li><a href="/user-guide/introduction.html">Guides</a></li>
        <li><a href="/reference/vitess-api.html">Reference</a></li>
        <li><a href="http://blog.vitess.io">Blog</a></li>
        <li><a href="https://github.com/youtube/vitess"><i class="fa fa-github"></i> GitHub</a></li>
        <!-- Hide link to blog unless we have actual posts -->
        <!-- <li><a href="/blog/" title="">Blog</a></li> -->
      </ul>
      <ul class="nav nav-stacked mobile-left-nav-menu" id="collapsed-left-menu">
                <li class="submenu">
          <h4 class="arrow-r no-top-margin">Overview</h4>
          <ul style="display: none">
            <li><a href="/overview/">What is Vitess</a></li>
            <li><a href="/overview/scaling-mysql.html">Scaling MySQL with Vitess</a></li>
            <li><a href="/overview/concepts.html">Key Concepts</a></li>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">Getting Started</h4>
          <ul style="display: none">
            <li style="padding-bottom: 0"><a href="/getting-started/">Run Vitess on Kubernetes</a>
              <ul style="display: block">
                <li style="padding-bottom: 0"><a href="/getting-started/docker-build.html">Custom Docker Build</a></li>
              </ul>
            </li>
            <li><a href="/getting-started/local-instance.html">Run Vitess Locally</a></li>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">User Guide</h4>
          <ul style="display: none">
            <li><a href="/user-guide/introduction.html">Introduction</a>
            <li><a href="/user-guide/client-libraries.html">Client Libraries</a>
            <li><a href="/user-guide/backup-and-restore.html">Backing Up Data</a>
            <li><a href="/user-guide/reparenting.html">Reparenting</a></li>
            <li style="padding-bottom: 0"><a href="/user-guide/schema-management.html">Schema Management</a></li>
              <ul style="display: block">
                <li style="padding-bottom: 0"><a href="/user-guide/vschema.html">VSchema Guide</a></li>
                <li style="padding-bottom: 0"><a href="/user-guide/schema-swap.html">Schema Swap (Tutorial)</a></li>
              </ul>
            <li style="padding-bottom: 0"><a href="/user-guide/sharding.html">Sharding</a>
              <ul style="display: block">
                <li><a href="/user-guide/horizontal-sharding-workflow.html">Horizontal Sharding (Tutorial, automated)</a></li>
                <li><a href="/user-guide/horizontal-sharding.html">Horizontal Sharding (Tutorial, manual)</a></li>
                <li><a href="/user-guide/sharding-kubernetes-workflow.html">Sharding in Kubernetes (Tutorial, automated)</a></li>
                <li style="padding-bottom: 0"><a href="/user-guide/sharding-kubernetes.html">Sharding in Kubernetes (Tutorial, manual)</a></li>
              </ul>
            </li>
            <li><a href="/user-guide/vitess-sequences.html">Vitess Sequences</a></li>
            <li><a href="/user-guide/mysql-server-protocol.html">MySQL Server Protocol</a></li>
            <li><a href="/user-guide/vitess-replication.html">Vitess and Replication</a></li>
            <li><a href="/user-guide/update-stream.html">Update Stream</a></li>
            <li><a href="/user-guide/row-based-replication.html">Row Based Replication</a></li>
            <li><a href="/user-guide/topology-service.html">Topology Service</a></li>
            <li><a href="/user-guide/transport-security-model.html">Transport Security Model</a></li>
            <li style="padding-bottom: 0"><a href="/user-guide/launching.html">Launching</a>
              <ul style="display: block">
                <li><a href="/user-guide/scalability-philosophy.html">Scalability Philosophy</a></li>
                <li><a href="/user-guide/production-planning.html">Production Planning</a></li>
                <li><a href="/user-guide/server-configuration.html">Server Configuration</a></li>
                <li><a href="/user-guide/twopc.html">2PC Guide</a></li>
                <li style="padding-bottom: 0"><a href="/user-guide/troubleshooting.html">Troubleshooting</a></li>
              </ul>
            </li>
            <li><a href="/user-guide/upgrading.html">Upgrading</a></li>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">Reference Guides</h4>
          <ul style="display: none">
            <li><a href="/reference/vitess-api.html">Vitess API</a>
            <li><a href="/reference/vtctl.html">vtctl Commands</a>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">Other Resources</h4>
          <ul style="display: none">
            <li><a href="/resources/presentations.html">Presentations</a>
            <li><a href="http://blog.vitess.io/">Blog</a>
            <li><a href="/resources/roadmap.html">Roadmap</a>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">Contributing</h4>
          <ul style="display: none">
            <li><a href="/contributing/">Contributing to Vitess</a>
            <li><a href="/contributing/github-workflow.html">GitHub Workflow</a>
            <li><a href="/contributing/code-reviews.html">Code Reviews</a>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">Internal</h4>
          <ul style="display: none">
            <li><a href="/internal/">Overview</a>
            <li><a href="/internal/release-instructions.html">Release Instructions</a>
            <li><a href="/internal/publish-website.html">Publish Website</a>
          </ul>
        </li>

        <div>
          <form method="get" action="/search/">
            <input id="search-form" name="q" type="text" placeholder="Search">
          </form>
        </div>

        <li><a href="https://github.com/youtube/vitess" id="collapsed-left-menu-repo-link"><i class="fa fa-github"></i> GitHub</a></li>
      </ul>
    </div><!-- /.navbar-collapse -->
  </div><!-- /.container-fluid -->
</nav>

    
<div id="masthead">
  <div class="container">
    <div class="row">
      <div class="col-md-9">
        <h1>Running Vitess on a Local Server</h1>
      </div>
    </div>
  </div>
</div>


<div class="container">
    <div class="row scroll-margin" id="toc-content-row">
    <div class="col-md-2" id="leftCol">
      <ul class="nav nav-stacked mobile-left-nav-menu" id="sidebar">
                <li class="submenu">
          <h4 class="arrow-r no-top-margin">Overview</h4>
          <ul style="display: none">
            <li><a href="/overview/">What is Vitess</a></li>
            <li><a href="/overview/scaling-mysql.html">Scaling MySQL with Vitess</a></li>
            <li><a href="/overview/concepts.html">Key Concepts</a></li>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">Getting Started</h4>
          <ul style="display: none">
            <li style="padding-bottom: 0"><a href="/getting-started/">Run Vitess on Kubernetes</a>
              <ul style="display: block">
                <li style="padding-bottom: 0"><a href="/getting-started/docker-build.html">Custom Docker Build</a></li>
              </ul>
            </li>
            <li><a href="/getting-started/local-instance.html">Run Vitess Locally</a></li>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">User Guide</h4>
          <ul style="display: none">
            <li><a href="/user-guide/introduction.html">Introduction</a>
            <li><a href="/user-guide/client-libraries.html">Client Libraries</a>
            <li><a href="/user-guide/backup-and-restore.html">Backing Up Data</a>
            <li><a href="/user-guide/reparenting.html">Reparenting</a></li>
            <li style="padding-bottom: 0"><a href="/user-guide/schema-management.html">Schema Management</a></li>
              <ul style="display: block">
                <li style="padding-bottom: 0"><a href="/user-guide/vschema.html">VSchema Guide</a></li>
                <li style="padding-bottom: 0"><a href="/user-guide/schema-swap.html">Schema Swap (Tutorial)</a></li>
              </ul>
            <li style="padding-bottom: 0"><a href="/user-guide/sharding.html">Sharding</a>
              <ul style="display: block">
                <li><a href="/user-guide/horizontal-sharding-workflow.html">Horizontal Sharding (Tutorial, automated)</a></li>
                <li><a href="/user-guide/horizontal-sharding.html">Horizontal Sharding (Tutorial, manual)</a></li>
                <li><a href="/user-guide/sharding-kubernetes-workflow.html">Sharding in Kubernetes (Tutorial, automated)</a></li>
                <li style="padding-bottom: 0"><a href="/user-guide/sharding-kubernetes.html">Sharding in Kubernetes (Tutorial, manual)</a></li>
              </ul>
            </li>
            <li><a href="/user-guide/vitess-sequences.html">Vitess Sequences</a></li>
            <li><a href="/user-guide/mysql-server-protocol.html">MySQL Server Protocol</a></li>
            <li><a href="/user-guide/vitess-replication.html">Vitess and Replication</a></li>
            <li><a href="/user-guide/update-stream.html">Update Stream</a></li>
            <li><a href="/user-guide/row-based-replication.html">Row Based Replication</a></li>
            <li><a href="/user-guide/topology-service.html">Topology Service</a></li>
            <li><a href="/user-guide/transport-security-model.html">Transport Security Model</a></li>
            <li style="padding-bottom: 0"><a href="/user-guide/launching.html">Launching</a>
              <ul style="display: block">
                <li><a href="/user-guide/scalability-philosophy.html">Scalability Philosophy</a></li>
                <li><a href="/user-guide/production-planning.html">Production Planning</a></li>
                <li><a href="/user-guide/server-configuration.html">Server Configuration</a></li>
                <li><a href="/user-guide/twopc.html">2PC Guide</a></li>
                <li style="padding-bottom: 0"><a href="/user-guide/troubleshooting.html">Troubleshooting</a></li>
              </ul>
            </li>
            <li><a href="/user-guide/upgrading.html">Upgrading</a></li>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">Reference Guides</h4>
          <ul style="display: none">
            <li><a href="/reference/vitess-api.html">Vitess API</a>
            <li><a href="/reference/vtctl.html">vtctl Commands</a>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">Other Resources</h4>
          <ul style="display: none">
            <li><a href="/resources/presentations.html">Presentations</a>
            <li><a href="http://blog.vitess.io/">Blog</a>
            <li><a href="/resources/roadmap.html">Roadmap</a>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">Contributing</h4>
          <ul style="display: none">
            <li><a href="/contributing/">Contributing to Vitess</a>
            <li><a href="/contributing/github-workflow.html">GitHub Workflow</a>
            <li><a href="/contributing/code-reviews.html">Code Reviews</a>
          </ul>
        </li>
        <li class="submenu">
          <h4 class="arrow-r">Internal</h4>
          <ul style="display: none">
            <li><a href="/internal/">Overview</a>
            <li><a href="/internal/release-instructions.html">Release Instructions</a>
            <li><a href="/internal/publish-website.html">Publish Website</a>
          </ul>
        </li>

        <div>
          <form method="get" action="/search/">
            <input id="search-form" name="q" type="text" placeholder="Search">
          </form>
        </div>

      </ul>
    </div>
    <div class="col-md-3" id="rightCol">
      <div class="nav nav-stacked" id="tocSidebar">
        <div id="toc"></div>
      </div>
    </div>
    <div class="col-md-7" id="centerCol">
      <div id="centerTextCol">
        <p>You can build Vitess using either <a href="#docker-build">Docker</a> or a
<a href="#manual-build">manual</a> build process.</p>

<p>If you run into issues or have questions, please post on our
<a href="https://groups.google.com/forum/#!forum/vitess">forum</a>.</p>

<h2 id="docker-build">Docker Build</h2>

<p>To run Vitess in Docker, you can either use our pre-built images on <a href="https://hub.docker.com/u/vitess/">Docker Hub</a>, or build them yourself.</p>

<h3 id="docker-hub-images">Docker Hub Images</h3>

<ul>
<li><p>The <a href="https://hub.docker.com/r/vitess/base/">vitess/base</a> image contains a full
development environment, capable of building Vitess and running integration tests.</p></li>
<li><p>The <a href="https://hub.docker.com/r/vitess/lite/">vitess/lite</a> image contains only
the compiled Vitess binaries, excluding ZooKeeper. It can run Vitess, but
lacks the environment needed to build Vitess or run tests. It&#39;s primarily used
for the <a href="http://vitess.io/getting-started/">Vitess on Kubernetes</a> guide.</p></li>
</ul>

<p>For example, you can directly run <code class="prettyprint">vitess/base</code>, and Docker will download the
image for you:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nv">$ </span>sudo docker run -ti vitess/base bash
vitess@32f187ef9351:/vt/src/github.com/youtube/vitess<span class="nv">$ </span>make build
</code></pre></div>
<p>Now you can proceed to <a href="#start-a-vitess-cluster">start a Vitess cluster</a> inside
the Docker container you just started. Note that if you want to access the
servers from outside the container, you&#39;ll need to expose the ports as described
in the <a href="https://docs.docker.com/engine/reference/run/#/expose-incoming-ports">Docker Engine Reference Guide</a>.</p>

<p>For local testing, you can also access the servers on the local IP address
created for the container by Docker:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nv">$ </span>docker inspect 32f187ef9351 <span class="p">|</span> grep IPAddress
<span class="c">### example output:</span>
<span class="c">#    &quot;IPAddress&quot;: &quot;172.17.3.1&quot;,</span>
</code></pre></div>
<h3 id="custom-docker-image">Custom Docker Image</h3>

<p>You can also build Vitess Docker images yourself to include your
own patches or configuration data. The
<a href="https://github.com/youtube/vitess/blob/master/Dockerfile">Dockerfile</a>
in the root of the Vitess tree builds the <code class="prettyprint">vitess/base</code> image.
The <a href="https://github.com/youtube/vitess/tree/master/docker">docker</a>
subdirectory contains scripts for building other images, such as <code class="prettyprint">vitess/lite</code>.</p>

<p>Our <code class="prettyprint">Makefile</code> also contains rules to build the images. For example:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="c"># Create vitess/bootstrap, which prepares everything up to ./bootstrap.sh</span>
vitess<span class="nv">$ </span>make docker_bootstrap
<span class="c"># Create vitess/base from vitess/bootstrap by copying in your local working directory.</span>
vitess<span class="nv">$ </span>make docker_base
</code></pre></div>
<h2 id="manual-build">Manual Build</h2>

<p>The following sections explain the process for manually building
Vitess without Docker.</p>

<h3 id="install-dependencies">Install Dependencies</h3>

<p>We currently test Vitess regularly on Ubuntu 14.04 (Trusty) and Debian 8 (Jessie).
OS X 10.11 (El Capitan) should work as well, the installation instructions are below.</p>

<h4 id="ubuntu-and-debian">Ubuntu and Debian</h4>

<p>In addition, Vitess requires the software and libraries listed below.</p>

<ol>
<li><p><a href="http://golang.org/doc/install">Install Go 1.8+</a>.</p></li>
<li><p>Install <a href="https://downloads.mariadb.org/">MariaDB 10.0</a> or
<a href="http://dev.mysql.com/downloads/mysql">MySQL 5.6</a>. You can use any
installation method (src/bin/rpm/deb), but be sure to include the client
development headers (<code class="prettyprint">libmariadbclient-dev</code> or <code class="prettyprint">libmysqlclient-dev</code>).</p>

<p>The Vitess development team currently tests against MariaDB 10.0.21
and MySQL 5.6.27.</p>

<p>If you are installing MariaDB, note that you must install version 10.0 or
higher. If you are using <code class="prettyprint">apt-get</code>, confirm that your repository
offers an option to install that version. You can also download the source
directly from <a href="https://downloads.mariadb.org/mariadb/">mariadb.org</a>.</p>

<p>If you are using Ubuntu 14.04 with MySQL 5.6, the default install may be
missing a file too, <code class="prettyprint">/usr/share/mysql/my-default.cnf</code>. It would show as an
error like <code class="prettyprint">Could not find my-default.cnf</code>. If you run into this, just add
it with the following contents:</p>
<div class="highlight"><pre><code class="language-ini" data-lang="ini"><span class="k">[mysqld]</span>
<span class="na">sql_mode</span><span class="o">=</span><span class="s">NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES</span>
</code></pre></div></li>
<li><p>Select a lock service from the options listed below. It is technically
possible to use another lock server, but plugins currently exist only
for ZooKeeper and etcd.</p>

<ul>
<li>ZooKeeper 3.3.5 is included by default. </li>
<li><a href="https://github.com/coreos/etcd/releases">Install etcd v3.0+</a>.
If you use etcd, remember to include the <code class="prettyprint">etcd</code> command
on your path.</li>
</ul></li>
<li><p>Install the following other tools needed to build and run Vitess:</p>

<ul>
<li>make</li>
<li>automake</li>
<li>libtool</li>
<li>python-dev</li>
<li>python-virtualenv</li>
<li>python-mysqldb</li>
<li>libssl-dev</li>
<li>g++</li>
<li>git</li>
<li>pkg-config</li>
<li>bison</li>
<li>curl</li>
<li>unzip</li>
</ul>

<p>These can be installed with the following apt-get command:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nv">$ </span>sudo apt-get install make automake libtool python-dev python-virtualenv python-mysqldb libssl-dev g++ git pkg-config bison curl unzip
</code></pre></div></li>
<li><p>If you decided to use ZooKeeper in step 3, you also need to install a
Java Runtime, such as OpenJDK.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nv">$ </span>sudo apt-get install openjdk-7-jre
</code></pre></div></li>
</ol>

<h4 id="os-x">OS X</h4>

<ol>
<li><p><a href="http://brew.sh/">Install Homebrew</a>. If your /usr/local directory is not empty and you never used Homebrew before,
it will be 
<a href="https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/El_Capitan_and_Homebrew.md">mandatory</a> 
to run the following command:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">sudo chown -R <span class="k">$(</span>whoami<span class="k">)</span>:admin /usr/local
</code></pre></div></li>
<li><p>On OS X, MySQL 5.6 has to be used, MariaDB doesn&#39;t work for some reason yet. It should be installed from Homebrew
(install steps are below).</p></li>
<li><p>If Xcode is installed (with Console tools, which should be bundled automatically since the 7.1 version), all 
the dev dependencies should be satisfied in this step. If no Xcode is present, it is necessery to install pkg-config.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">brew install pkg-config
</code></pre></div></li>
<li><p>ZooKeeper is used as lock service.</p></li>
<li><p>Run the following commands:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">brew install go automake libtool python git bison curl wget homebrew/versions/mysql56
pip install --upgrade pip setuptools
pip install virtualenv
pip install MySQL-python
pip install tox
</code></pre></div></li>
<li><p>Install Java runtime from this URL: <a href="https://support.apple.com/kb/dl1572?locale=en_US">https://support.apple.com/kb/dl1572?locale=en_US</a>
Apple only supports Java 6. If you need to install a newer version, this link might be helpful:
<a href="http://osxdaily.com/2015/10/17/how-to-install-java-in-os-x-el-capitan/">http://osxdaily.com/2015/10/17/how-to-install-java-in-os-x-el-capitan/</a></p></li>
<li><p>The Vitess bootstrap script makes some checks for the go runtime, so it is recommended to have the following
commands in your ~/.profile or ~/.bashrc or ~/.zshrc:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nb">export </span><span class="nv">PATH</span><span class="o">=</span>/usr/local/opt/go/libexec/bin:<span class="nv">$PATH</span>
<span class="nb">export </span><span class="nv">GOROOT</span><span class="o">=</span>/usr/local/opt/go/libexec
</code></pre></div></li>
<li><p>There is a problem with installing the enum34 Python package using pip, so the following file has to be edited:
<code class="prettyprint">
/usr/local/opt/python/Frameworks/Python.framework/Versions/2.7/lib/python2.7/distutils/distutils.cfg
</code></p>

<p>and this line:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">prefix=/usr/local
</code></pre></div>
<p>has to be commented out:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text"># prefix=/usr/local
</code></pre></div>
<p>After running the ./bootstrap.sh script from the next step, you can revert the change.</p></li>
<li><p>For the Vitess hostname resolving functions to work correctly, a new entry has to be added into the /etc/hosts file
with the current LAN IP address of the computer (preferably IPv4) and the current hostname, which you get by
typing the &#39;hostname&#39; command in the terminal.</p>

<p>It is also a good idea to put the following line to <a href="https://golang.org/doc/go1.5#net">force the Go DNS resolver</a> 
in your ~/.profile or ~/.bashrc or ~/.zshrc:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">export GODEBUG=netdns=go
</code></pre></div></li>
</ol>

<h3 id="build-vitess">Build Vitess</h3>

<ol>
<li><p>Navigate to the directory where you want to download the Vitess
source code and clone the Vitess Github repo. After doing so,
navigate to the <code class="prettyprint">src/github.com/youtube/vitess</code> directory.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nb">cd</span> <span class="nv">$WORKSPACE</span>
git clone https://github.com/youtube/vitess.git <span class="se">\</span>
    src/github.com/youtube/vitess
<span class="nb">cd </span>src/github.com/youtube/vitess
</code></pre></div></li>
<li><p>Set the <code class="prettyprint">MYSQL_FLAVOR</code> environment variable. Choose the appropriate
value for your database. This value is case-sensitive.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nb">export </span><span class="nv">MYSQL_FLAVOR</span><span class="o">=</span>MariaDB
<span class="c"># or (mandatory for OS X)</span>
<span class="c"># export MYSQL_FLAVOR=MySQL56</span>
</code></pre></div></li>
<li><p>If your selected database installed in a location other than <code class="prettyprint">/usr/bin</code>,
set the <code class="prettyprint">VT_MYSQL_ROOT</code> variable to the root directory of your
MariaDB installation. For example, if MariaDB is installed in
<code class="prettyprint">/usr/local/mysql</code>, run the following command.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nb">export </span><span class="nv">VT_MYSQL_ROOT</span><span class="o">=</span>/usr/local/mysql

<span class="c"># on OS X, this is the correct value:</span>
<span class="c"># export VT_MYSQL_ROOT=/usr/local/opt/mysql56</span>
</code></pre></div>
<p>Note that the command indicates that the <code class="prettyprint">mysql</code> executable should
be found at <code class="prettyprint">/usr/local/mysql/bin/mysql</code>.</p></li>
<li><p>Run <code class="prettyprint">mysql_config --version</code> and confirm that you
are running the correct version of MariaDB or MySQL. The value should
be 10 or higher for MariaDB and 5.6.x for MySQL.</p></li>
<li><p>Build Vitess using the commands below. Note that the
<code class="prettyprint">bootstrap.sh</code> script needs to download some dependencies.
If your machine requires a proxy to access the Internet, you will need
to set the usual environment variables (e.g. <code class="prettyprint">http_proxy</code>,
<code class="prettyprint">https_proxy</code>, <code class="prettyprint">no_proxy</code>).</p>

<p>Run the boostrap.sh script:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">./bootstrap.sh
<span class="c">### example output:</span>
<span class="c"># skipping zookeeper build</span>
<span class="c"># go install golang.org/x/tools/cmd/cover ...</span>
<span class="c"># Found MariaDB installation in ...</span>
<span class="c"># creating git pre-commit hooks</span>
<span class="c">#</span>
<span class="c"># source dev.env in your shell before building</span>
</code></pre></div><div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="c"># Remaining commands to build Vitess</span>
. ./dev.env
make build
</code></pre></div></li>
</ol>

<h3 id="run-tests">Run Tests</h3>

<p><strong>Note:</strong> If you are using etcd, set the following environment variable:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nb">export </span><span class="nv">VT_TEST_FLAGS</span><span class="o">=</span><span class="s1">&#39;--topo-server-flavor=etcd&#39;</span>
</code></pre></div>
<p>The default targets when running <code class="prettyprint">make</code> or <code class="prettyprint">make test</code> contain a full set of
tests intended to help Vitess developers to verify code changes. Those tests
simulate a small Vitess cluster by launching many servers on the local
machine. To do so, they require a lot of resources; a minimum of 8GB RAM
and SSD is recommended to run the tests.</p>

<p>If you want only to check that Vitess is working in your environment,
you can run a lighter set of tests:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">make site_test
</code></pre></div>
<h4 id="common-test-issues">Common Test Issues</h4>

<p>Attempts to run the full developer test suite (<code class="prettyprint">make</code> or <code class="prettyprint">make test</code>)
on an underpowered machine often results in failure. If you still see
the same failures when running the lighter set of tests (<code class="prettyprint">make site_test</code>),
please let the development team know in the
<a href="https://groups.google.com/forum/#!forum/vitess">vitess@googlegroups.com</a>
discussion forum.</p>

<h5 id="node-already-exists-port-in-use-etc">Node already exists, port in use, etc.</h5>

<p>A failed test can leave orphaned processes. If you use the default
settings, you can use the following commands to identify and kill
those processes:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">pgrep -f -l <span class="s1">&#39;(vtdataroot|VTDATAROOT)&#39;</span> <span class="c"># list Vitess processes</span>
pkill -f <span class="s1">&#39;(vtdataroot|VTDATAROOT)&#39;</span> <span class="c"># kill Vitess processes</span>
</code></pre></div>
<h5 id="too-many-connections-to-mysql-or-other-timeouts">Too many connections to MySQL, or other timeouts</h5>

<p>This error often means your disk is too slow. If you don&#39;t have access
to an SSD, you can try <a href="https://github.com/youtube/vitess/blob/master/doc/TestingOnARamDisk.md">testing against a
ramdisk</a>.</p>

<h5 id="connection-refused-to-tablet-mysql-socket-not-found-etc">Connection refused to tablet, MySQL socket not found, etc.</h5>

<p>These errors might indicate that the machine ran out of RAM and a server
crashed when trying to allocate more RAM. Some of the heavier tests
require up to 8GB RAM.</p>

<h5 id="connection-refused-in-zkctl-test">Connection refused in zkctl test</h5>

<p>This error might indicate that the machine does not have a Java Runtime
installed, which is a requirement if you are using ZooKeeper as the lock server.</p>

<h5 id="running-out-of-disk-space">Running out of disk space</h5>

<p>Some of the larger tests use up to 4GB of temporary space on disk.</p>

<h2 id="start-a-vitess-cluster">Start a Vitess cluster</h2>

<p>After completing the instructions above to <a href="#build-vitess">build Vitess</a>,
you can use the example scripts in the Github repo to bring up a Vitess
cluster on your local machine. These scripts use ZooKeeper as the
lock service. ZooKeeper is included in the Vitess distribution.</p>

<ol>
<li><p><strong>Check system settings</strong></p>

<p>Some Linux distributions ship with default file descriptor limits
that are too low for database servers. This issue could show up
as the database crashing with the message &quot;too many open files&quot;.</p>

<p>Check the system-wide <code class="prettyprint">file-max</code> setting as well as user-specific
<code class="prettyprint">ulimit</code> values. We recommend setting them above 100K to be safe.
The exact <a href="http://www.cyberciti.biz/faq/linux-increase-the-maximum-number-of-open-files/">procedure</a>
 may vary depending on your Linux distribution.</p></li>
<li><p><strong>Configure environment variables</strong></p>

<p>If you are still in the same terminal window that
you used to run the build commands, you can skip to the next
step since the environment variables will already be set.</p>

<p>If you&#39;re adapting this example to your own deployment, the only environment
variables required before running the scripts are <code class="prettyprint">VTROOT</code> and <code class="prettyprint">VTDATAROOT</code>.</p>

<p>Set <code class="prettyprint">VTROOT</code> to the parent of the Vitess source tree. For example, if you
ran <code class="prettyprint">make build</code> while in <code class="prettyprint">$HOME/vt/src/github.com/youtube/vitess</code>,
then you should set:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nb">export </span><span class="nv">VTROOT</span><span class="o">=</span><span class="nv">$HOME</span>/vt
</code></pre></div>
<p>Set <code class="prettyprint">VTDATAROOT</code> to the directory where you want data files and logs to
be stored. For example:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nb">export </span><span class="nv">VTDATAROOT</span><span class="o">=</span><span class="nv">$HOME</span>/vtdataroot
</code></pre></div></li>
<li><p><strong>Start ZooKeeper</strong></p>

<p>Servers in a Vitess cluster find each other by looking for
dynamic configuration data stored in a distributed lock
service. The following script creates a small ZooKeeper cluster:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nv">$ </span><span class="nb">cd</span> <span class="nv">$VTROOT</span>/src/github.com/youtube/vitess/examples/local
vitess/examples/local<span class="nv">$ </span>./zk-up.sh
<span class="c">### example output:</span>
<span class="c"># Starting zk servers...</span>
<span class="c"># Waiting for zk servers to be ready...</span>
</code></pre></div>
<p>After the ZooKeeper cluster is running, we only need to tell each
Vitess process how to connect to ZooKeeper. Then, each process can
find all of the other Vitess processes by coordinating via ZooKeeper.</p>

<p>Each of our scripts automatically uses the <code class="prettyprint">TOPOLOGY_FLAGS</code> environment
variable to point to the global ZooKeeper instance. The global instance in
turn is configured to point to the local instance. In our sample scripts,
they are both hosted in the same ZooKeeper service.</p></li>
<li><p><strong>Start vtctld</strong></p>

<p>The <em>vtctld</em> server provides a web interface that
displays all of the coordination information stored in ZooKeeper.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">vitess/examples/local<span class="nv">$ </span>./vtctld-up.sh
<span class="c"># Starting vtctld</span>
<span class="c"># Access vtctld web UI at http://localhost:15000</span>
<span class="c"># Send commands with: vtctlclient -server localhost:15999 ...</span>
</code></pre></div>
<p>Open <code class="prettyprint">http://localhost:15000</code> to verify that
<em>vtctld</em> is running. There won&#39;t be any information
there yet, but the menu should come up, which indicates that
<em>vtctld</em> is running.</p>

<p>The <em>vtctld</em> server also accepts commands from the <code class="prettyprint">vtctlclient</code> tool,
which is used to administer the cluster. Note that the port for RPCs
(in this case <code class="prettyprint">15999</code>) is different from the web UI port (<code class="prettyprint">15000</code>).
These ports can be configured with command-line flags, as demonstrated
in <code class="prettyprint">vtctld-up.sh</code>.</p>

<p>For convenience, we&#39;ll use the <code class="prettyprint">lvtctl.sh</code> script in example commands,
to avoid having to type the <em>vtctld</em> address every time.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="c"># List available commands</span>
vitess/examples/local<span class="nv">$ </span>./lvtctl.sh <span class="nb">help</span>
</code></pre></div></li>
<li><p><strong>Start vttablets</strong></p>

<p>The <code class="prettyprint">vttablet-up.sh</code> script brings up three vttablets, and assigns them to
a <a href="http://vitess.io/overview/concepts.html#keyspace">keyspace</a> and <a href="http://vitess.io/overview/concepts.html#shard">shard</a> according to the variables
set at the top of the script file.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">vitess/examples/local<span class="nv">$ </span>./vttablet-up.sh
<span class="c"># Output from vttablet-up.sh is below</span>
<span class="c"># Starting MySQL for tablet test-0000000100...</span>
<span class="c"># Starting vttablet for test-0000000100...</span>
<span class="c"># Access tablet test-0000000100 at http://localhost:15100/debug/status</span>
<span class="c"># Starting MySQL for tablet test-0000000101...</span>
<span class="c"># Starting vttablet for test-0000000101...</span>
<span class="c"># Access tablet test-0000000101 at http://localhost:15101/debug/status</span>
<span class="c"># Starting MySQL for tablet test-0000000102...</span>
<span class="c"># Starting vttablet for test-0000000102...</span>
<span class="c"># Access tablet test-0000000102 at http://localhost:15102/debug/status</span>
</code></pre></div>
<p>After this command completes, refresh the <em>vtctld</em> web UI, and you should
see a keyspace named <code class="prettyprint">test_keyspace</code> with a single shard named <code class="prettyprint">0</code>.
This is what an unsharded keyspace looks like.</p>

<p>If you click on the shard box, you&#39;ll see a list of <a href="http://vitess.io/overview/concepts.html#tablet">tablets</a> in that shard.
Note that it&#39;s normal for the tablets to be unhealthy at this point, since
you haven&#39;t initialized them yet.</p>

<p>You can also click the <strong>STATUS</strong> link on each tablet to be taken to its
status page, showing more details on its operation. Every Vitess server has
a status page served at <code class="prettyprint">/debug/status</code> on its web port.</p></li>
<li><p><strong>Initialize MySQL databases</strong></p>

<p>Next, designate one of the tablets to be the initial master.
Vitess will automatically connect the other slaves&#39; mysqld instances so
that they start replicating from the master&#39;s mysqld.
This is also when the default database is created. Since our keyspace is
named <code class="prettyprint">test_keyspace</code>, the MySQL database will be named <code class="prettyprint">vt_test_keyspace</code>.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">vitess/examples/local<span class="nv">$ </span>./lvtctl.sh InitShardMaster -force test_keyspace/0 <span class="nb">test</span>-100
<span class="c">### example output:</span>
<span class="c"># master-elect tablet test-0000000100 is not the shard master, proceeding anyway as -force was used</span>
<span class="c"># master-elect tablet test-0000000100 is not a master in the shard, proceeding anyway as -force was used</span>
</code></pre></div>
<p><strong>Note:</strong> Since this is the first time the shard has been started,
the tablets are not already doing any replication, and there is no
existing master. The <code class="prettyprint">InitShardMaster</code> command above uses the <code class="prettyprint">-force</code> flag
to bypass the usual sanity checks that would apply if this wasn&#39;t a
brand new shard.</p>

<p>After running this command, go back to the <strong>Shard Status</strong> page
in the <em>vtctld</em> web interface. When you refresh the
page, you should see that one <em>vttablet</em> is the master
and the other two are replicas.</p>

<p>You can also see this on the command line:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">vitess/examples/local<span class="nv">$ </span>./lvtctl.sh ListAllTablets <span class="nb">test</span>
<span class="c">### example output:</span>
<span class="c"># test-0000000100 test_keyspace 0 master localhost:15100 localhost:33100 []</span>
<span class="c"># test-0000000101 test_keyspace 0 replica localhost:15101 localhost:33101 []</span>
<span class="c"># test-0000000102 test_keyspace 0 replica localhost:15102 localhost:33102 []</span>
</code></pre></div></li>
<li><p><strong>Create a table</strong></p>

<p>The <code class="prettyprint">vtctlclient</code> tool can be used to apply the database schema across all
tablets in a keyspace. The following command creates the table defined in
the <code class="prettyprint">create_test_table.sql</code> file:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="c"># Make sure to run this from the examples/local dir, so it finds the file.</span>
vitess/examples/local<span class="nv">$ </span>./lvtctl.sh ApplySchema -sql <span class="s2">&quot;$(cat create_test_table.sql)&quot;</span> test_keyspace
</code></pre></div>
<p>The SQL to create the table is shown below:</p>
<div class="highlight"><pre><code class="language-sql" data-lang="sql"><span class="k">CREATE</span> <span class="k">TABLE</span> <span class="n">messages</span> <span class="p">(</span>
  <span class="n">page</span> <span class="nb">BIGINT</span><span class="p">(</span><span class="mi">20</span><span class="p">)</span> <span class="n">UNSIGNED</span><span class="p">,</span>
  <span class="n">time_created_ns</span> <span class="nb">BIGINT</span><span class="p">(</span><span class="mi">20</span><span class="p">)</span> <span class="n">UNSIGNED</span><span class="p">,</span>
  <span class="n">message</span> <span class="nb">VARCHAR</span><span class="p">(</span><span class="mi">10000</span><span class="p">),</span>
  <span class="k">PRIMARY</span> <span class="k">KEY</span> <span class="p">(</span><span class="n">page</span><span class="p">,</span> <span class="n">time_created_ns</span><span class="p">)</span>
<span class="p">)</span> <span class="n">ENGINE</span><span class="o">=</span><span class="n">InnoDB</span>
</code></pre></div></li>
<li><p><strong>Take a backup</strong></p>

<p>Now that the initial schema is applied, it&#39;s a good time to take the first
<a href="http://vitess.io/user-guide/backup-and-restore.html">backup</a>. This backup
will be used to automatically restore any additional replicas that you run,
before they connect themselves to the master and catch up on replication.
If an existing tablet goes down and comes back up without its data, it will
also automatically restore from the latest backup and then resume replication.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">vitess/examples/local<span class="nv">$ </span>./lvtctl.sh Backup <span class="nb">test</span>-0000000102
</code></pre></div>
<p>After the backup completes, you can list available backups for the shard:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">vitess/examples/local<span class="nv">$ </span>./lvtctl.sh ListBackups test_keyspace/0
<span class="c">### example output:</span>
<span class="c"># 2016-05-06.072724.test-0000000102</span>
</code></pre></div>
<p><strong>Note:</strong> In this single-server example setup, backups are stored at
<code class="prettyprint">$VTDATAROOT/backups</code>. In a multi-server deployment, you would usually mount
an NFS directory there. You can also change the location by setting the
<code class="prettyprint">-file_backup_storage_root</code> flag on <em>vtctld</em> and <em>vttablet</em>, as demonstrated
in <code class="prettyprint">vtctld-up.sh</code> and <code class="prettyprint">vttablet-up.sh</code>.</p></li>
<li><p><strong>Initialize Vitess Routing Schema</strong></p>

<p>In the examples, we are just using a single database with no specific
configuration. So we just need to make that (empty) configuration visible
for serving. This is done by running the following command:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">vitess/examples/local<span class="nv">$ </span>./lvtctl.sh RebuildVSchemaGraph
</code></pre></div>
<p>(As it works, this command will not display any output.)</p></li>
<li><p><strong>Start vtgate</strong></p>

<p>Vitess uses <em>vtgate</em> to route each client query to
the correct <em>vttablet</em>. This local example runs a
single <em>vtgate</em> instance, though a real deployment
would likely run multiple <em>vtgate</em> instances to share
the load.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">vitess/examples/local<span class="nv">$ </span>./vtgate-up.sh
</code></pre></div></li>
</ol>

<h3 id="run-a-client-application">Run a Client Application</h3>

<p>The <code class="prettyprint">client.py</code> file is a simple sample application
that connects to <em>vtgate</em> and executes some queries.
To run it, you need to either:</p>

<ul>
<li><p>Add the Vitess Python packages to your <code class="prettyprint">PYTHONPATH</code>.</p>

<p>or</p></li>
<li><p>Use the <code class="prettyprint">client.sh</code> wrapper script, which temporarily
sets up the environment and then runs <code class="prettyprint">client.py</code>.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">vitess/examples/local<span class="nv">$ </span>./client.sh
<span class="c">### example output:</span>
<span class="c"># Inserting into master...</span>
<span class="c"># Reading from master...</span>
<span class="c"># (5L, 1462510331910124032L, &#39;V is for speed&#39;)</span>
<span class="c"># (15L, 1462519383758071808L, &#39;V is for speed&#39;)</span>
<span class="c"># (42L, 1462510369213753088L, &#39;V is for speed&#39;)</span>
<span class="c"># ...</span>
</code></pre></div></li>
</ul>

<p>There are also sample clients in the same directory for Java, PHP, and Go.
See the comments at the top of each sample file for usage instructions.</p>

<h3 id="try-vitess-resharding">Try Vitess resharding</h3>

<p>Now that you have a full Vitess stack running, you may want to go on to the
<a href="http://vitess.io/user-guide/horizontal-sharding-workflow.html">Horizontal Sharding workflow guide</a>
or <a href="http://vitess.io/user-guide/horizontal-sharding.html">Horizontal Sharding codelab</a>
(if you prefer to run each step manually through commands) to try out
<a href="http://vitess.io/user-guide/sharding.html#resharding">dynamic resharding</a>.</p>

<p>If so, you can skip the tear-down since the sharding guide picks up right here.
If not, continue to the clean-up steps below.</p>

<h3 id="tear-down-the-cluster">Tear down the cluster</h3>

<p>Each <code class="prettyprint">-up.sh</code> script has a corresponding <code class="prettyprint">-down.sh</code> script to stop the servers.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">vitess/examples/local<span class="nv">$ </span>./vtgate-down.sh
vitess/examples/local<span class="nv">$ </span>./vttablet-down.sh
vitess/examples/local<span class="nv">$ </span>./vtctld-down.sh
vitess/examples/local<span class="nv">$ </span>./zk-down.sh
</code></pre></div>
<p>Note that the <code class="prettyprint">-down.sh</code> scripts will leave behind any data files created.
If you&#39;re done with this example data, you can clear out the contents of <code class="prettyprint">VTDATAROOT</code>:</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh"><span class="nv">$ </span><span class="nb">cd</span> <span class="nv">$VTDATAROOT</span>
/path/to/vtdataroot<span class="nv">$ </span>rm -rf *
</code></pre></div>
<h2 id="troubleshooting">Troubleshooting</h2>

<p>If anything goes wrong, check the logs in your <code class="prettyprint">$VTDATAROOT/tmp</code> directory
for error messages. There are also some tablet-specific logs, as well as
MySQL logs in the various <code class="prettyprint">$VTDATAROOT/vt_*</code> directories.</p>

<p>If you need help diagnosing a problem, send a message to our
<a href="https://groups.google.com/forum/#!forum/vitess">mailing list</a>.
In addition to any errors you see at the command-line, it would also help to
upload an archive of your <code class="prettyprint">VTDATAROOT</code> directory to a file sharing service
and provide a link to it.</p>

      </div>
    </div>
  </div>

</div>

    <div class="page-spacer"></div>
    <footer role="contentinfo" id="site-footer">
  <nav role="navigation" class="menu bottom-menu">
    
    <a href="https://groups.google.com/forum/#!forum/vitess" target="_blank">Contact: vitess@googlegroups.com</a>&nbsp;&nbsp;<b>·</b>&nbsp;&nbsp;
    <a href="https://groups.google.com/forum/#!forum/vitess-announce" target="_blank">Announcements</a>&nbsp;&nbsp;<b>·</b>&nbsp;&nbsp;
    &#169; 2017 <a href="/">Vitess</a> powered by <a href="https://developers.google.com/open-source/">Google Inc</a>
  </nav>
</footer>


        <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
<!--    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>   -->
    <!-- Include all compiled plugins (below), or include individual files as needed -->
<!--
    <script src="/libs/bootstrap/js/bootstrap.min.js"></script>
-->
    <!-- Include the common site javascript -->
    <script src="/js/common.js" type="text/javascript" charset="utf-8"></script>


  </body>
</html>
